fix: Notify dependent flags when an FDv2 prerequisite or segment changes - #470

## Summary

The flag change listener tests only ever changed the flag that the
listener was watching, so an SDK that never notified dependent flags
passed them all. This adds a `dependent flags` group under both listener
suites.

The tests start the SDK with one data set: a three-flag prerequisite
chain, a flag whose rule references a segment, a flag whose prerequisite
is that segment-rule flag (so a segment change must travel through a
prerequisite), a flag whose rule references a segment that itself
matches a nested segment, and an unrelated flag. They then change a
prerequisite or a segment through the FDv2 stream and assert the exact
set of flags that a general flag change listener hears about, and
nothing else: the prerequisite chain, a change in the middle of it,
deletion of a prerequisite, segment and nested segment changes and
deletion (reaching the flag that depends on the segment-rule flag as
well), a dependency added or removed by an update, and a full data set
that changes or drops items. The flag value change listener tests assert
the value that a dependency change produces (prerequisite failing,
prerequisite deleted, segment starting to include the context, the same
through a prerequisite, nested segment) and that a change which leaves
the value as it was stays quiet.

New helpers: `ExpectFlagChangeNotifications` collects one notification
per expected key, compares the keys as a set, and then requires silence;
`registerFlagChangeListener` and `registerFlagValueChangeListener`
register a listener and close its callback when the test scope exits;
`streamPusher` pushes puts, deletes, and full data sets with
monotonically increasing versions. No change to the test service
protocol.

## Verification

Run locally against the current test services: Go (reference), Node,
Python, and .NET pass every new test. Ruby `main` fails exactly the 15
dependency tests and still passes the 8 existing direct-change tests,
which is the defect that launchdarkly/ruby-server-sdk#470 fixes; the
Ruby branch with that fix passes. The Java test service does not declare
the listener capabilities, so the suite is skipped there. `make lint`
and `go test ./...` are clean.

[SDK-3355](https://launchdarkly.atlassian.net/browse/SDK-3355)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Overview**
> Adds **dependent flags** coverage to the SDK test harness listener
suites so SDKs must notify flags affected by prerequisite chains,
segment rules, nested segments, and full payload replacements—not only
the flag that was directly updated.
> 
> A new `common_tests_listeners_dependencies.go` drives FDv2 stream
updates (puts, deletes, full xfer) against a shared fixture
(prerequisite chain `top → mid → leaf`, segment-linked flags, nested
segments, unrelated control). **Flag change** tests assert the exact set
of notified flag keys; **flag value** tests assert old/new values when a
dependency changes evaluation and silence when it does not.
> 
> Test API helpers add `registerFlagChangeListener` /
`registerFlagValueChangeListener` (auto-close on scope exit),
`ExpectFlagChangeNotifications` (order-independent set match plus no
extra notifications), and `streamPusher` for monotonic versioning. No
change to the test service protocol.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
89bfbea. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

[SDK-3355]:
https://launchdarkly.atlassian.net/browse/SDK-3355?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

🤖 I have created a release *beep* *boop*
---


##
[8.19.1](8.19.0...8.19.1)
(2026-10-23)


### Bug Fixes

* Notify dependent flags when an FDv2 prerequisite or segment changes
([#470](#470))
([6d79abe](6d79abe))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Overview**
> **Patch release 8.19.1** bumps the SDK from `8.19.0` to `8.19.1` via
Release Please (`LaunchDarkly::VERSION`,
`.release-please-manifest.json`, and the provenance doc example).
> 
> The changelog records one shipped fix
([#470](#470)):
**dependent flags are notified when an FDv2 prerequisite or segment
changes**, so flag-change listeners and related updates stay in sync
when upstream FDv2 data changes. This PR does not include application
code—only version and release metadata.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
df13a28. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

<!-- TERMAG_PR_BODY_BEGIN -->
## Summary

This PR is stacked on #450 because it uses the override marker, the
evaluator marking, and the reason indicator that PR adds.

This change adds the override layer that the OVERRIDE specification
describes: a runtime-mutable collection of flag and segment definitions
that takes precedence over LaunchDarkly data at the store read boundary,
populated by an override source through a sink. With no override source
configured the SDK behaves exactly as before. The file-based source, the
events changes, and the contract test service follow in later PRs.

`LaunchDarkly::Interfaces::Overrides::OverrideSource` and `OverrideSink`
define how a source supplies complete snapshots to the SDK. The sink
accepts data model objects or hashes in the flag and segment data model.
The SDK marks the entries itself.

`Impl::Overrides::Layer` holds marked entries in an immutable hash that
is swapped on update, so the layer holds exactly one snapshot at any
instant and reads are lock-free. `Impl::Overrides::Overlay` sits at the
store read boundary: a read for a key returns the override entry when
one exists and the LaunchDarkly entry otherwise, an enumeration is the
union with the override entry winning, and initialization status is the
base store's alone. `Impl::Overrides::Sink` applies snapshots and
notifies flag change listeners of every flag whose merged-view
evaluation may have changed, including flags that depend on an
overridden prerequisite or segment. It computes dependency edges over
both the old and the new merged view, as the Go reference does.

`DataSystem::ConfigBuilder#overrides` accepts one override source
builder, the same `build(sdk_key, config)` protocol as the data source
builders. The FDv2 data system builds the source at construction, so an
invalid configuration raises from `LDClient.new` like other invalid
component configuration. It starts the source before its run loop, so
the initial load is in effect before the constructor returns. An
exception from the source's `start` does not prevent the client from
starting: the SDK logs it, stops the source, removes any snapshot the
source supplied, and the client runs without overrides (the SDK's own
file source does not raise from `start`; a custom source could). It
serves reads through the overlay. When the client closes, the sink stops
accepting snapshots before the source is stopped, and an exception from
`stop` is logged. An offline client builds no source and logs a warning
that the configured source is not started.

The client consults the override store before the not-initialized
short-circuit. An overridden flag is served before LaunchDarkly data
arrives, read from the override store itself, and a flag that is not
overridden still returns the client-not-ready default, even when a store
without an init marker holds LaunchDarkly data for it. `all_flags_state`
reads through the overlay. Before initialization, when the store is not
initialized and the override store holds flags, it returns a state of
those flags alone, read from the override store, with a once-per-client
warning; with no override flags the state is invalid, as it is without a
source. Without a source this state is empty, because the SDK reports no
flags before the store is initialized, so the override flags only add to
what it reports; overrides never remove a flag from the state. A failure
of the base store to list its flags propagates through the overlay, and
`all_flags_state` logs it as without a source. Without a source the
state is then invalid and empty; with override flags it holds those
flags and stays invalid, so the overrides only add to it. A client-side
SDK bootstrapped from the state uses its flags whatever `$valid` says
(js-client-sdk 3.x and the 4.x browser SDK only log a warning), so the
overridden values still reach it. A wrong-type migration result keeps
the marking of the evaluation it replaces. When the evaluator raises for
a flag that came from the override store, `variation_detail` and
`all_flags_state` report the `EXCEPTION` error reason with
`override_affected` set, from the flag's own marker. This also fixes a
pre-existing crash: `all_flags_state` raised `NoMethodError` when an
evaluation raised, because the failed flag has no evaluation state; it
now reports that flag with no prerequisites. The marker is read only
from the SDK's model objects: a custom store can return a flag as a
plain hash, as the `FeatureStore` interface documents, and such a flag
never came from the override store, so its failed evaluation still
returns the unmarked `EXCEPTION` result instead of raising.

A value-only override expands, through the file loading code from #449,
into a flag that is on and serves its single value by fallthrough, which
reports the FALLTHROUGH reason kind as the specification describes.

The OVERRIDE specification's test vectors
(`spec/fixtures/override-vectors/vectors.json`) run as a spec through
the full client stack, checking value, variation index, and reason under
the vectors' comparison rules. The vectors' per-evaluation summary
marker is asserted once the event processor carries the marking, in the
events PR.

LaunchDarkly changes reach override dependents. `Layer` keeps a
dependency graph of its entries in each snapshot, and `Store` expands
every changed LaunchDarkly item through both its own graph and the
layer's, to a fixpoint. A change to a prerequisite flag or a segment
that an override entry references therefore notifies that entry's flag,
the same way dependent flags are notified for LaunchDarkly data, and a
chain may cross between LaunchDarkly data and overrides any number of
times.

The FDv2 store's defect that seeded its dependency fan-out with symbol
keys, while `Impl::DependencyTracker` indexes dependents under string
keys, is fixed on `main` by #470, which the
stack's base now includes. The fan-out helper here also compares keys as
strings, which the fixpoint needs in any case, and the store spec keeps
the #470 specs beside this PR's specs for the override layer.

Verification: specs for the layer (marking, replacement, snapshot
atomicity under concurrent writers), the overlay (precedence, union,
deleted base items, base failure, initialization), the sink (added,
removed, changed, and unchanged entries, dependency fan-out through
prerequisites and nested segments, both merged views, no-listener path,
base failure, serialized updates), the FDv2 wiring (construction, start
order, overlay reads, stop, offline, availability unaffected), the
client (not-ready gate, all-flags state, change notifications through
the flag tracker, migration marker, lifecycle), and the specification
vectors. Full suite and RuboCop are clean, and the full suite passes on
JRuby 9.4 (the specs wait on queues without `Queue#pop`'s timeout, which
Ruby 3.1 and JRuby 9.4 lack). Each new spec was checked against a
deliberate defect in the code it covers.

The existing FDv1 and FDv2 file data sources keep their current
behavior. This series does not change them; the override feature is
additive.

[SDK-3249](https://launchdarkly.atlassian.net/browse/SDK-3249)


[SDK-3249]:
https://launchdarkly.atlassian.net/browse/SDK-3249?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Overview**
> **feat: Add the override store, overlay, and data system wiring**
> 
> Adds experimental, runtime flag/segment overrides:
`DataSystem::ConfigBuilder#overrides` accepts an `OverrideSource`
builder, FDv2 builds `Layer` + `Overlay` + `Sink`, wires `Store` to
cross-graph dependency notifications, and extends evaluator/reason
plumbing so prerequisites, segments, and client APIs respect override
markers while still documenting that the surface is experimental.
> 
> **Highlights**
> 
> - New override layer modules (`Impl::Overrides::{Layer,Overlay,Sink}`)
plus `Interfaces::Overrides` contracts mark model objects, merge
overrides ahead of LD data, and fan-out flag-change listeners using
merged dependency graphs.
> - `EvaluationReason`, evaluator state, prerequisite records,
migrations, and `LDClient` paths (`variation_detail`, `all_flags_state`)
now propagate `overrideAffected`, handle uninitialized stores by
consulting pure override snapshots, and keep JSON compatibility by
emitting the bit only when true.
> - FDv2 data system starts/stops override sources safely (offline skip,
resilient `start`/`stop`), exposes `override_items`, and coordinates
with `Store` via external dependency graphs; specs/vectors cover layer
semantics, notifier behavior, client flows, and file-data reloader
timing fixes on coarse clocks.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
1005ed0. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

The all-flags report keeps an override-affected flag's `trackEvents`,
`trackReason`, and `debugEventsUntilDate` in this PR; #452 turns them
off (OVERRIDE Requirement 1.4.1.1) together with the rest of the event
policy for override-affected evaluations.
<!-- TERMAG_PR_BODY_END -->

<!-- termag: box=i-0575d1c54853058d7 project=Overrides -->
<sub>Opened from termag</sub>